DragManager

Kind of class:class
Inherits from:EventDispatcher
Classpath:gfx.managers.DragManager
File last modified:Tuesday, 29 June 2010, 09:03:27
Singleton class providing methods to initiate and manage drag and drop operations. Used by DragTarget, InventorySlot, and ItemSlot components.

Events
  • dragEnd: Dispatched when a drag operation ends, either because the mouse was released, or because cancelDrag was called. The event object includes the following properties:
    • cancelled: indicates whether the drag was ended by calling cancelDrag
    • data: the data associated with the drag operation
    • dropTarget: the current drop target (ie. what is currently dragged over)
  • dragBegin: Dispatched when a drag operation begins. Includes the following properties:
    • data: the data associated with the drag operation

Summary


Class properties
  • instance
    • Returns a reference to the DragManager instance.
Instance properties
  • removeTarget
    • Indicates whether the target will be removed when the drag finishes.
  • dragOffsetX
    • Specifies the x offset of the drag target from the cursor position.
  • dragOffsetY
    • Specifies the y offset of the drag target from the cursor position.
  • cancelKeyCode
    • Indicates the key code that will cancel a drag.
  • dropTarget
    • Indicates the current drop target for the drag.
  • relatedObject
    • Arbitrary data to associate with this drag operation.
  • inDrag
    • Indicates whether there is an active drag operation.
  • data
    • Returns the data associated with the currently active drag operation, or null if there is not an active drag.
  • target
    • Returns the target (avatar) of the currently active drag operation, or null if there is not an active drag.
Class methods
Class methods inherited from EventDispatcher
$dispatchEvent indexOfListener initialize
Instance methods
  • startDrag
    • Starts a drag operation.
  • stopDrag
    • Stops an active drag operation, and dispatches the "endDrag" event with the cancelled flag set to false.
  • initiateDrag
    • Sets the data and inDrag properties, and dispatches the "dragBegin" event.
  • cancelDrag
    • Stops an active drag operation, and dispatches the "dragEnd" event with the cancelled flag set to true.
  • update
    • Repositions the drag target relative to the cursor position.
Instance methods inherited from EventDispatcher
addEventListener cleanUp cleanUpEvents dispatchEvent dispatchQueue hasEventListener removeAllEventListeners removeEventListener

Class properties

instance

static instance:DragManager
(read)

Returns a reference to the DragManager instance.

Instance properties

cancelKeyCode

cancelKeyCode:Number = Key.ESCAPE
(read,write)

Indicates the key code that will cancel a drag. Set to 0 to disable.

data

data:Object
(read)

Returns the data associated with the currently active drag operation, or null if there is not an active drag.

dragOffsetX

dragOffsetX:Number = 0
(read,write)

Specifies the x offset of the drag target from the cursor position. This is automatically set to true when calling startDrag. You can override this default value after calling startDrag. You may wish to call update() after setting this value to immediately update the target's position.

dragOffsetY

dragOffsetY:Number = 0
(read,write)

Specifies the y offset of the drag target from the cursor position. This is automatically set to true when calling startDrag. You can override this default value after calling startDrag. You may wish to call update() after setting this value to immediately update the target's position.

dropTarget

dropTarget:Object = null
(read,write)

Indicates the current drop target for the drag.

inDrag

inDrag:Boolean
(read)

Indicates whether there is an active drag operation.

relatedObject

relatedObject:Object
(read,write)

Arbitrary data to associate with this drag operation. This is usually used to reference the object the drag originated from.

removeTarget

removeTarget:Boolean = false
(read,write)

Indicates whether the target will be removed when the drag finishes. This is automatically set to true when using a linkageID for the target parameter of a startDrag operation, and false otherwise. You can override this default value after calling startDrag. For example, you may want to do this so that you can animate the avatar back into position.

target

target:MovieClip
(read)

Returns the target (avatar) of the currently active drag operation, or null if there is not an active drag.

Instance methods

cancelDrag

function cancelDrag (
) : Void

Stops an active drag operation, and dispatches the "dragEnd" event with the cancelled flag set to true. The cancel flag indicates to listeners that they should not act on the drop.

initiateDrag

function initiateDrag (
data:Object, relatedObject:Object) : Void

Sets the data and inDrag properties, and dispatches the "dragBegin" event. This method is useful for if you want to utilize custom drag logic, but still take advantage of DragManager's events.
Parameters:
data :
Data representing the object being dragged. This will be included with all events associated with this drag, and is accessible during the drag via the .data property.
relatedObject:
Arbitrary data to associate with this drag operation. This is usually used to reference the object the drag originated from.

startDrag

function startDrag (
pressOrigin:MovieClip, avatar:Object, data:Object, relatedObject:Object, alignmentTarget:MovieClip, lockCenter:Boolean, bounds:Object) : MovieClip

Starts a drag operation. This will automatically call initiateDrag to notify any drag listeners.
Parameters:
pressOrigin :
The MovieClip that was pressed to begin this drag. In order for drags to work correctly, the press origin must have its trackAsMenu property set to true. This optional parameter allows DragManager to set this property, and revert it when the drag ends.
avatar :
A movie clip reference or a linkage string to use as the avatar to drag. If a string is specified DragManager will attempt to instantiate the avatar in the reserved clip on the _root so that it appears over top of all UI elements. If null is specified, no avatar will be used.
data :
Data representing the object being dragged. This will be included with all events associated with this drag, and is accessible during the drag via the .data property.
relatedObject :
Arbitrary data to associate with this drag operation. This is usually used to reference the object the drag originated from.
alignmentTarget:
A MovieClip to base initial position on. For example passing in the icon instance that was clicked to initiate the drag would position the avatar in the same position.
lockCenter :
Locks the drag target's origin to the cursor position.
bounds :
(optional) Object containing drag constraints for the target using in the target's parent's coordinates. Can contain "left", "right", "bottom", and "top" properties for drag bounds. If any bound property is undefined, it will default to have no boundary.
Returns:
  • The target clip that will be dragged, this is either the reference passed in as the target parameter, the clip that was instantiated from the specified linkage id, or null.

stopDrag

function stopDrag (
) : Void

Stops an active drag operation, and dispatches the "endDrag" event with the cancelled flag set to false. This method can be used with drag operations initiated by both startDrag and initiateDrag.

update

function update (
) : Void

Repositions the drag target relative to the cursor position. Useful if you manually adjust the dragOffset properties and want to immediately updat the target position.